/*
 * Copyright 2010 jun.enomoto<jun.enomoto@gmail.com>
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package foursquare4j;

import foursquare4j.exception.FoursquareException;
import foursquare4j.types.Categories;
import foursquare4j.types.CheckinResult;
import foursquare4j.types.Checkins;
import foursquare4j.types.Friends;
import foursquare4j.types.Requests;
import foursquare4j.types.Response;
import foursquare4j.types.Settings;
import foursquare4j.types.Tip;
import foursquare4j.types.TipsResult;
import foursquare4j.types.Todos;
import foursquare4j.types.User;
import foursquare4j.types.Users;
import foursquare4j.types.Venue;
import foursquare4j.types.Venues;

/**
 * Foursquare.
 * 
 * @see <a href="http://groups.google.com/group/foursquare-api/web/api-documentation">API documentation - foursquare API</a>
 */
public interface Foursquare {

	static final String USER_AGENT = System.getProperty("foursquare4j.http.user.agent", "foursquare4j:0.2.0-SNAPSHOT 20100915");

	static final String CALLBACK_URL = "oob";

	static final String REQUEST_TOKEN_URL = "http://foursquare.com/oauth/request_token";

	static final String USER_AUTHORIZATION_URL = "http://foursquare.com/oauth/authorize";

	static final String ACCESS_TOKEN_URL = "http://foursquare.com/oauth/access_token";

	static final String API_BASE_URL = "http://api.foursquare.com/v1";

	static final String API_AUTHEXCHANGE_URL = API_BASE_URL + "/authexchange";

	static final String API_CHECKINS_URL = API_BASE_URL + "/checkins";

	static final String API_CHECKIN_URL = API_BASE_URL + "/checkin";

	static final String API_HISTORY_URL = API_BASE_URL + "/history";

	static final String API_USER_URL = API_BASE_URL + "/user";

	static final String API_FRIENDS_URL = API_BASE_URL + "/friends";

	static final String API_VENUES_URL = API_BASE_URL + "/venues";

	static final String API_VENUE_URL = API_BASE_URL + "/venue";

	static final String API_CATEGORIES_URL = API_BASE_URL + "/categories";

	static final String API_ADDVENUE_URL = API_BASE_URL + "/addvenue";

	static final String API_PROPOSEEDIT_URL = API_VENUE_URL + "/proposeedit";

	static final String API_FLAGCLOSED_URL = API_VENUE_URL + "/flagclosed";

	static final String API_FLAGMISLOCATED_URL = API_VENUE_URL + "/flagmislocated";

	static final String API_FLAGDUPLICATE_URL = API_VENUE_URL + "/flagduplicate";

	static final String API_TIPS_URL = API_BASE_URL + "/tips";

	static final String API_ADDTIP_URL = API_BASE_URL + "/addtip";

	static final String API_TIP_MARKTODO_URL = API_BASE_URL + "/tip/marktodo";

	static final String API_TIP_MARKDONE_URL = API_BASE_URL + "/tip/markdone";

	static final String API_TIP_UNMARK_URL = API_BASE_URL + "/tip/unmark";

	static final String API_TIP_DETAIL_URL = API_BASE_URL + "/tip/detail";

	static final String API_TODOS_URL = API_BASE_URL + "/todos";

	static final String API_FRIEND_REQUESTS_URL = API_BASE_URL + "/friend/requests";

	static final String API_FRIEND_APPROVE_URL = API_BASE_URL + "/friend/approve";

	static final String API_FRIEND_DENY_URL = API_BASE_URL + "/friend/deny";

	static final String API_FRIEND_SENDREQUEST_URL = API_BASE_URL + "/friend/sendrequest";

	static final String API_FINDFRIENDS_BYNAME_URL = API_BASE_URL + "/findfriends/byname";

	static final String API_FINDFRIENDS_BYPHONE_URL = API_BASE_URL + "/findfriends/byphone";

	static final String API_FINDFRIENDS_BYTWITTER_URL = API_BASE_URL + "/findfriends/bytwitter";

	static final String API_SETTINGS_SETPINGS_URL = API_BASE_URL + "/settings/setpings";

	static final String API_TEST_URL = API_BASE_URL + "/test";

	/**
	 * Checkins.
	 * 
	 * Returns a list of recent checkins from friends.<br />
	 * <br />
	 * If you pass in a geolat/geolong pair (optional, but recommended), we'll send you back a distance inside each checkin object that you can use to sort your results.<br />
	 * <br />
	 * Some notes on how to parse each checkin block:
	 * <ul>
	 * <li>if venue exists, it's a check-in to a proper place.</li>
	 * <li>if venue and shout exist, it's a check-in to a proper place with a shout.</li>
	 * <li>if only shout exists, it's a shout (no check-in). shouts are like callouts or tweets to your network. they need not be tied down to a particular place. it's useful for sending messages like: "hey who's up for hanging out later tonight?".</li>
	 * <li>if no venue or shout exists, then it's a silent check-in ("off-the-grid" as we like to say). this shows up in the timeline so that you know the person is out and about (to make it easy to meet up after they are done with whatever they are doing. it's useful for stuff like dates, business meetings, etc).</li>
	 * </ul>
	 * <br />
	 * URL: http://api.foursquare.com/v1/checkins<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: Yes<br />
	 * <br />
	 * Parameters:
	 * <ul>
	 * <li>geolat - (optional, but recommended)</li>
	 * <li>geolong - (optional, but recommended)</li>
	 * </ul>
	 * Response (truncated):
	 * <pre>{
	 *   checkins:[
	 *     {
	 *       id:286939,
	 *       user:{
	 *         id:467,
	 *         firstname:'Sarah',
	 *         lastname:'Simmons',
	 *         photo:'http://foursquare.com/userpix/467_1237171998.jpg',
	 *         gender:'female'
	 *       },
	 *       venue:{
	 *         id:44379,
	 *         name:'Topshop',
	 *         address:'478 Broadway',
	 *         crossstreet:'at Broome',
	 *         geolat:40.7215,
	 *         geolong:-74.0001
	 *       },
	 *       distance:2382,
	 *       display:'Sarah S. @ Topshop',
	 *       shout:'Just tried on a dress ...',
	 *       created:'Thu, 21 May 09 18:09:22 +0000'
	 *     }
	 *   ]
	 * }</pre> 
	 * 
	 * @param geolat (optional, but recommended)
	 * @param geolong (optional, but recommended)
	 * @return list of recent checkins from friends.
	 * @throws FoursquareException
	 */
	Checkins checkins(CharSequence geolat, CharSequence geolong) throws FoursquareException;

	/**
	 * Check-in.
	 * 
	 * Allows you to check-in to a place.<br />
	 * <br />
	 * A mayor block will be returned if there's any mayor information for this place. It'll include a node type which has the following values: new (the user has been appointed mayorship), nochange (the previous mayorship is still valid), stolen (the user stole mayorship from the previous mayor).<br />
	 * <br />
	 * A specials block will be returned if there are any specials associated with this check-in. It'll include subnodes special which may have various types. The types can be one of: mayor, count, frequency, or other. If the special is at a nearby venue (instead of at the currently checked-into venue), you'll see a {kind: 'nearby'} object and you'll see a venue node inside special that will highlight the nearby venue. If the special exists at the venue you're currently looking at, no venue block will appear and kind will read "here".<br />
	 * <br />
	 * If you're building an interface that interactively shows unlocked badges and tips, try to conform to this copy so that users will have an easier time recognizing the experience:
	 * <ul>
	 * <li>Badge: "You've unlocked [badge/name]: [badge/description]."</li>
	 * <li>Tip (nearby): "Since you're so close to [venue], [firstname last-initial] says: [tip/text]."</li>
	 * <li>Tip (here): "Since you're at [venue], [firstname last-initial] says: [tip/text]."</li>
	 * </ul>
	 * <br /> 
	 * URL: http://api.foursquare.com/v1/checkin<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>vid - (optional, not necessary if you are 'shouting' or have a venue name). ID of the venue where you want to check-in</li>
	 * <li>venue - (optional, not necessary if you are 'shouting' or have a vid) if you don't have a venue ID or would rather prefer a 'venueless' checkin, pass the venue name as a string using this parameter. it will become an 'orphan' (no address or venueid but with geolat, geolong)</li>
	 * <li>shout - (optional) a message about your check-in. the maximum length of this field is 140 characters</li>
	 * <li>private - (optional). "1" means "don't show your friends". "0" means "show everyone"</li>
	 * <li>twitter - (optional, defaults to the user's setting). "1" means "send to Twitter". "0" means "don't send to Twitter"</li>
	 * <li>facebook - (optional, defaults to the user's setting). "1" means "send to Facebook". "0" means "don't send to Facebook"</li>
	 * <li>geolat - (optional, but recommended)</li>
	 * <li>geolong - (optional, but recommended)</li>
	 * </ul>
	 * Response:
	 * <pre>{
	 *   checkin:{
	 *     message:'OK! We\'ve got you @ 4SQ HQ - Soho. This is your 8th checkin here!',
	 *     id:413421,
	 *     created:'Mon, 29 Jun 09 14:21:06 +0000',
	 *     venue:{
	 *       id:45506,
	 *       name:'4SQ HQ - Soho',
	 *       address:'...',
	 *       crossstreet:'btw Grand & Broome',
	 *       city:'New York',
	 *       state:'NY',
	 *       zip:10013
	 *     },
	 *     mayor:{
	 *       type:'nochange',
	 *       checkins:10,
	 *       user:{
	 *         id:138,
	 *         firstname:'Dan',
	 *         lastname:'M.',
	 *         photo:'http://playfoursquare.s3.amazonaws.com/userpix_thumbs/138_1237786934.jpg',
	 *         gender:'male'
	 *       },
	 *       message:'Dan M. is The Mayor of Bowery Wine Company.'
	 *     },
	 *     badges:{
	 *       badge:{
	 *         id:123,
	 *         name:'Newbie',
	 *         icon:'http://foursquare.com/img/badge/newbie.png',
	 *         description:'Congrats on your first checkin!'
	 *       }
	 *     },
	 *     scoring:{
	 *       score:[
	 *         {
	 *           points:1,
	 *           icon:'http://foursquare.com/img/scoring/2.png',
	 *           message:'First stop tonight'
	 *         },
	 *         {
	 *           points:5,
	 *           icon:'http://foursquare.com/img/scoring/1.png',
	 *           message:'First time @ 4SQ HQ!'
	 *         }
	 *       ]
	 *     },
	 *     specials:{
	 *       special:{
	 *         id:2,
	 *         type:'mayor',
	 *         kind:'nearby',
	 *         message:'If you\'re the mayor, show the bartender and your first drink is free! (just beer and well drinks guys, let\'s be fair)',
	 *         venue:{
	 *           id:333
	 *         }
	 *       }
	 *     },
	 *     checkin:{
	 *     }
	 *   }
	 * }</pre>
	 * 
	 * @param vid (optional, not necessary if you are 'shouting' or have a venue name). ID of the venue where you want to check-in
	 * @param venue (optional, not necessary if you are 'shouting' or have a vid) if you don't have a venue ID or would rather prefer a 'venueless' checkin, pass the venue name as a string using this parameter. it will become an 'orphan' (no address or venueid but with geolat, geolong)
	 * @param shout (optional) a message about your check-in. the maximum length of this field is 140 characters
	 * @param _private (optional). "1" means "don't show your friends". "0" means "show everyone"
	 * @param twitter (optional, defaults to the user's setting). "1" means "send to Twitter". "0" means "don't send to Twitter"
	 * @param facebook (optional, defaults to the user's setting). "1" means "send to Facebook". "0" means "don't send to Facebook"
	 * @param geolat (optional, but recommended)
	 * @param geolong (optional, but recommended)
	 * @return Allows you to check-in to a place.
	 * @throws FoursquareException
	 */
	CheckinResult checkin(CharSequence vid, CharSequence venue, CharSequence shout, CharSequence _private, CharSequence twitter, CharSequence facebook, CharSequence geolat, CharSequence geolong) throws FoursquareException;

	/**
	 * History.
	 * 
	 * Returns a history of checkins for the authenticated user.<br />
	 * <br />
	 * Some notes on how to parse each checkin block:
	 * <ul>
	 * <li>if venue exists, it's a check-in to a proper place.</li>
	 * <li>if venue and shout exist, it's a check-in to a proper place with a shout.</li>
	 * <li>if only shout exists, it's a shout (no check-in).</li>
	 * </ul>
	 * <br />
	 * URL: http://api.foursquare.com/v1/history<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>l - limit of results (optional, default: 20, max: 250). number of checkins to return</li>
	 * <li>sinceid - id to start returning results from (optional, if omitted returns most recent results)</li>
	 * </ul>
	 * <br />
	 * Response (truncated):
	 * <pre>{
	 *   checkins:[
	 *     {
	 *       id:947380,
	 *       venue:{
	 *         id:34655,
	 *         name:'Monday Room',
	 *         primarycategory:{
	 *           id:79156,
	 *           fullpathname:'Nightlife:Cocktails / Mixology',
	 *           nodename:'Cocktails / Mixology',
	 *           iconurl:'http://foursquare.com/img/categories/nightlife/cocktails.png'
	 *         },
	 *         address:'201 Elizabeth St',
	 *         crossstreet:'btw Prince & Spring',
	 *         city:'New York',
	 *         state:'NY',
	 *         zip:10012,
	 *         geolat:40.722,
	 *         geolong:-73.9944,
	 *         phone:2123437011
	 *       },
	 *       shout:'drinks with brier',
	 *       created:'Thu, 03 Sep 09 01:23:40 +0000'
	 *     },
	 *     {
	 *       id:944792
	 * ...</pre>
	 * 
	 * @param l limit of results (optional, default: 20, max: 250). number of checkins to return
	 * @param sinceid id to start returning results from (optional, if omitted returns most recent results)
	 * @return Returns a history of checkins for the authenticated user.
	 * @throws FoursquareException
	 */
	Checkins history(CharSequence l, CharSequence sinceid) throws FoursquareException;

	/**
	 * User detail.
	 * 
	 * Returns profile information (badges, etc) for a given user. If the user has recent check-in data (ie, if the user is self or is a friend of the authenticating user), this data will be returned as well in a checkin block.<br />
	 * <br />
	 * If the user requested is 'self' (ie, the authenticating user), a settings block with defaults will be returned. This settings block includes attributes like sendtotwitter, sendtofacebook. sendtotwitter will indicate whether the default action is to tweet check-in information to Twitter (the possible values are true and false). sendtofacebook will indicate whether the default action is to send check-in information to the user's Facebook news feed. pings will indicate whether the user will receive check-in notification pings from client apps (iPhone, Android, Blackberry, ...). The possible values for pings are: on (send pings) and off (don't send pings).<br />
	 * <br />
	 * Lastly, if the user is a friend of the authenticating user, you'll have access to the requested user's phone, email, Twitter and Facebook ID. In addition to this, you'll also see a setting get_pings. get_pings will indicate whether the authenticating user is setup to receive check-in pings from the friend (push notifications, etc). The possible values for get_pings are true and false.<br />
	 * <br />
	 * The friendstatus node has four possible values:
	 * <ul>
	 * <li>friend - the requested user is your friend</li>
	 * <li>pendingyou - the requested user sent you a friend request that you have not accepted</li>
	 * <li>pendingthem - you have sent a friend request to the requested user but they have not accepted</li>
	 * <li>node absent - the requested user is not your friend (and neither party has made an attempt at connecting)</li>
	 * </ul>
	 * <br />
	 * The latter two will be particularly useful in showing status in your application. If 'pendingyou', you'll probably want to lead them to an approve/ignore action. If 'pendingthem', you'll probably want to just show 'pending approval' as a note.<br />
	 * <br />
	 * A hint: you can also use this call as a way to verify credentials (ensure that the user hasn't revoked OAuth permission or that their Basic Auth login hasn't changed).<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/user<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>uid - userid for the user whose information you want to retrieve. if you do not specify a 'uid', the authenticated user's profile data will be returned.</li>
	 * <li>twitter - twitter handle for the user whose information you want to retrieve. if you specify both 'uid' and 'twitter', 'uid' will take precedence.</li>
	 * <li>badges - (optional, default: false) set to true ("1") to also show badges for this user. by default, this will show badges earned worldwide.</li>
	 * <li>mayor - (optional, default: false) set to true ("1") to also show venues for which this user is a mayor. by default, this will show mayorships worldwide.</li>
	 * <li>
	 * <br />
	 * Response (truncated):
	 * <pre>{
	 *   user:{
	 *     id:33,
	 *     firstname:'Naveen',
	 *     lastname:'Selvadurai',
	 *     photo:'http://foursquare.com/userpix/33_1235974851.jpg',
	 *     gender:'male',
	 *     phone:2129103995,
	 *     email:'n@naveen.com',
	 *     twitter:'naveen',
	 *     facebook:29103995,
	 *     friendstatus:'friend',
	 *     checkin:{
	 *       id:413421,
	 *       created:'Mon, 29 Jun 09 14:21:06 +0000',
	 *       venue:{
	 *         id:45506,
	 *         name:'4SQ HQ - Soho',
	 *         address:'...',
	 *         crossstreet:'btw Grand & Broome',
	 *         city:'New York',
	 *         state:'NY',
	 *         zip:10013
	 *       }
	 *     },
	 *     badges:[
	 *       {
	 *         name:'Newbie',
	 *         icon:'http://foursquare.com/img/badge/newbie_on.png',
	 *         description:'Congrats on your first check-in!'
	 *       }
	 * </pre>
	 * <br />
	 * Response for 'self' authenticated (truncated):
	 * <pre>{
	 *   user:{
	 *     id:33,
	 * ...
	 *     settings:{
	 *       sendtotwitter:'false',
	 *       sendtofacebook:'false',
	 *       pings:'on'
	 *     }
	 * </pre>
	 *     
	 * @param uid userid for the user whose information you want to retrieve. if you do not specify a 'uid', the authenticated user's profile data will be returned.
	 * @param twitter twitter handle for the user whose information you want to retrieve. if you specify both 'uid' and 'twitter', 'uid' will take precedence. 
	 * @param badges (optional, default: false) set to true ("1") to also show badges for this user. by default, this will show badges earned worldwide. 
	 * @param mayor (optional, default: false) set to true ("1") to also show venues for which this user is a mayor. by default, this will show mayorships worldwide.
	 * @return Returns profile information (badges, etc) for a given user. If the user has recent check-in data (ie, if the user is self or is a friend of the authenticating user), this data will be returned as well in a checkin block.
	 * @throws FoursquareException
	 */
	User user(CharSequence uid, CharSequence twitter, CharSequence badges, CharSequence mayor) throws FoursquareException;

	/**
	 * Friends.
	 * 
	 * Returns a list of friends. If you do not specify uid, the authenticating user's list of friends will be returned. If the friend has allowed it, you'll also see links to their Twitter and Facebook accounts.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/friends<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>uid - user id of the person for whom you want to pull a friend graph (optional)</li<
	 * </ul>
	 * <br />
	 * Response (truncated):
	 * <pre>{
	 *   friends:[
	 *     {
	 *       id:32,
	 *       firstname:'Dennis',
	 *       lastname:'Crowley',
	 *       photo:'http://playfoursquare.s3.amazonaws.com/userpix_thumbs/32_1239135232.jpg',
	 *       gender:'male',
	 *       phone:2120000000,
	 *       email:'dennis@crowley.co.uk',
	 *       twitter:'dens',
	 *       facebook:803834
	 *     }
	 *   ]
	 * }</pre>
	 *
	 * @param uid user id of the person for whom you want to pull a friend graph (optional)
	 * @return Returns a list of friends. If you do not specify uid, the authenticating user's list of friends will be returned. If the friend has allowed it, you'll also see links to their Twitter and Facebook accounts.
	 * @throws FoursquareException
	 */
	Friends friends(CharSequence uid) throws FoursquareException;

	/**
	 * Nearby and search.
	 *
	 * Returns a list of venues near the area specified or that match the search term. (The distance returned is in meters). If you authenticate, the method will return venue meta-data related to you and your friends. If you do not authenticate, you will not get this data.<br />
	 * <br />
	 * Note that most of the fields returned inside venue can be optional. The user may create a venue that has no address, city or state (the venue is created instead at the geolat/geolong specified). Your client should handle these conditions safely.<br />
	 * <br />
	 * You'll also notice a stats block that reveals some count data about the venue. herenow shows the number of people currently there (this value can be 0).<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/venues<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: No, but recommended<br />
	 * Parameters:
	 * <ul>
	 * <li>geolat - latitude (required)</li>
	 * <li>geolong - longitude (required)</li>
	 * <li>l - limit of results (optional, default 10, maximum 50)</li>
	 * <li>q - keyword search (optional)</li>
	 * </ul>
	 * Response (truncated):
	 * <ul>
	 * <pre>{
	 *   groups:[
	 *     {
	 *       type:'Nearby favorites',
	 *       venue:{
	 *         id:257,
	 *         name:'Bowery Ballroom',
	 *         primarycategory:{
	 *           id:{
	 *             value:79167,
	 *             id:{
	 *               fullpathname:'Nightlife:Music Venue:Rock Club',
	 *               nodename:'Rock Club',
	 *               iconurl:'http://foursquare.com/img/categories/nightlife/default.png',
	 *               distance:10,
	 *               address:'6 Delancey St',
	 *               crossstreet:'at Bowery',
	 *               city:'New York',
	 *               state:'NY',
	 *               zip:10002,
	 *               geolat:40.7204,
	 *               geolong:-73.9933,
	 *               phone:2120000000,
	 *               twitter:'BoweryBallroom',
	 *               stats:{
	 *                 herenow:36
	 *               },
	 *               venue:{
	 *                 id:5055,
	 *                 name:'Hiro Ballroom'
	 * 
	 * ...</pre>
	 * 
	 * @param geolat latitude (required)
	 * @param geolong longitude (required)
	 * @param l limit of results (optional, default 10, maximum 50)
	 * @param q keyword search (optional)
	 * @return Returns a list of venues near the area specified or that match the search term. (The distance returned is in meters). If you authenticate, the method will return venue meta-data related to you and your friends. If you do not authenticate, you will not get this data.
	 * @throws FoursquareException
	 */
	Venues venues(CharSequence geolat, CharSequence geolong, CharSequence l, CharSequence q) throws FoursquareException;

	/**
	 * Venue details.
	 *
	 * When given a venue identifier (vid), returns venue data, including mayorship, tips/to-dos and tags. If the vid given is one that has been merged into another "master" venue, the response will show data about the "master" instead of giving you an error.<br />
	 * <br />
	 * A specials block will be returned if there are any specials associated with this check-in. It'll include subnodes special which may have various types. The types can be one of: mayor, count, frequency, or other. If the special is at a nearby venue (instead of at the currently visible venue), you'll see a {kind: 'nearby'} object and you'll see a venue node inside special that will highlight the nearby venue. If the special exists at the venue you're currently looking at, no venue block will appear and kind will read "here".<br />
	 * <br />
	 * If you authenticate, you'll get back social meta data:<br />
	 * <ul>
	 * <li>stats - shows whether you and your friends have ever checked in here (beenhere); total checkins at the venue (stats/checkins); and total people there now (stats/herenow). the checkins and herenow blocks serve as a live count of people currently at the venue: if someone moves, the count will drop</li>
	 * <li>checkins - show the people currently checked into this location (ie, last three hours). you'll see shout and full lastname if they are friends with the authenticating user. this block will only return the last 50 results. to get a count of all people there, use stats/herenow</li>
	 * </ul>
	 * <br />
	 * URL: http://api.foursquare.com/v1/venue<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: No, but recommended<br />
	 * Parameters:
	 * <ul>
	 * <li>vid - the ID for the venue for which you want information</li>
	 * </ul>
	 * <br />
	 * Response (truncated):
	 * <pre>{
	 *   "venue": {
	 *     "id": 49049,
	 *     "name": "Pig & Whistle",
	 *     "primarycategory": {
	 *       "id": 79153,
	 *       "fullpathname": "Nightlife:Bar",
	 *       "nodename": "Bar",
	 *       "iconurl": "http://foursquare.com/img/categories/nightlife/default.png"
	 *     },
	 *     "address": "365 Greenwich St",
	 *     "city": "New York",
	 *     "state": "NY",
	 *     "zip": "10013",
	 *     "geolat": 40.7192,
	 *     "geolong": -74.0103,
	 *     "stats": {
	 *       "checkins": 24,
	 *       "herenow": "0",
	 *       "beenhere": {
	 *         "me": true
	 *       },
	 *       "mayor": {
	 *         "user": {
	 *           "id": 36690,
	 *           "firstname": "Mike",
	 *           "lastname": "P.",
	 *           "photo": "http://playfoursquare.s3.amazonaws.com/userpix_thumbs/4a9f29d1e43d7.jpg",
	 *           "gender": "male"
	 *         },
	 *         "count": 2
	 *       }
	 *     },
	 *     "tips": [
	 *       {
	 *         "id": 14506,
	 *         "text": "if you stay for a while the owner is more than likely to drop by with free food or drink",
	 *         "created": "Fri, 26 Jun 09 18:45:49 +0000",
	 *         "user": {
	 *           "id": 16970,
	 *           "firstname": "Greg",
	 *           "lastname": "S.",
	 *           "photo": "http://playfoursquare.s3.amazonaws.com/userpix_thumbs/4a4262911f7cf.jpg",
	 *           "gender": "male"
	 *         }
	 *       },
	 *       {
	 *         "id": 8713,
	 *         "text": "one of the many \"Pig\" places in the city i want to go to. (hey! i should make a \"Pig\" list).",
	 *         "created": "Thu, 30 Apr 09 14:40:17 +0000",
	 *         "user": {
	 *           "id": 33,
	 *           "firstname": "Naveen",
	 *           "photo": "http://playfoursquare.s3.amazonaws.com/userpix_thumbs/YSTILJBL51CMM024.jpg",
	 *           "gender": "male"
	 *         }
	 *       }
	 *     ],
	 *     "categories": [
	 *       {
	 *         "id": 79153,
	 *         "fullpathname": "Nightlife:Bar",
	 *         "nodename": "Bar",
	 *         "iconurl": "http://foursquare.com/img/categories/nightlife/default.png"
	 *       }
	 *     ],
	 *     "specials": [
	 *     ]
	 *   }
	 * }</pre>
	 * 
	 * @param vid the ID for the venue for which you want information
	 * @return When given a venue identifier (vid), returns venue data, including mayorship, tips/to-dos and tags. If the vid  given is one that has been merged into another "master" venue, the response will show data about the "master" instead of giving you an error.
	 * @throws FoursquareException
	 */
	Venue venue(CharSequence vid) throws FoursquareException;

	/**
	 * Categories list.
	 *
	 * Returns a hierarchical list of categories currently supported by the platform.<br />
	 * <br />
	 * The values can be described as:
	 * <ul>
	 * <li>categories - an array of subcategories</li>
	 * <li>id - the category id at this level (to be used as primarycategoryid when passed to /addvenue)</li>
	 * <li>fullpathname - a colon (":") delimited path to the category</li>
	 * <li>nodename - name of the current category (to be displayed in your interface)</li>
	 * <li>iconurl - URL to the category icon (cache these per session or max, per week as they are subject to change)</li>
	 * </ul>
	 * <br />
	 * Note that top-level categories do not have IDs because they cannot be assigned to a venue.<br />
	 * <br />
	 * When designing your client apps, you might want to take care to pull this list down only once per session (and perhaps cache it for a short while).<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/categories<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: No<br />
	 * Parameters: None<br />
	 * Response (truncated):<br />
	 * <br />
	 * <pre>{
	 *   categories:[
	 *     {
	 *       fullpathname: 'Arts & Entertainment',
	 *       nodename: 'Arts & Entertainment',
	 *       iconurl: 'http://foursquare.com/img/categories/arts_entertainment.png',
	 *       categories: [
	 *         {
	 *           id: 78959,
	 *           fullpathname: 'Arts & Entertainment:Arcade',
	 *           nodename: 'Arcade',
	 *           iconurl: 'http://foursquare.com/img/categories/arts_entertainment/arcade.png'
	 *         },
	 *         {
	 *           id: 78960,
	 *           fullpathname: 'Arts & Entertainment:Art Gallery',
	 *           nodename: 'Art Gallery',
	 *           iconurl: 'http://foursquare.com/img/categories/arts_entertainment/artgallery.png'
	 *         }
	 *       ]
	 * ...</pre>
	 * 
	 * @return Returns a hierarchical list of categories currently supported by the platform.
	 * @throws FoursquareException
	 */
	Categories categories() throws FoursquareException;

	/**
	 * Add venue.
	 *
	 * Allows you to add a new venue.<br />
	 * <br />
	 * If you find this method returns an error, give the user the option to edit her inputs. In addition to this, give users the ability to say "never mind, check-in here anyway" and perform a manual ("venueless") checkin by specifying just the venue name to /v1/checkin. You'll rarely run into this case, but there's a chance you'll see this case if the user wants to force a duplicate venue.<br />
	 * <br />
	 * All fields are optional, but you must specify either a valid address or a geolat/geolong pair. It's recommended that you pass a geolat/geolong pair in every case.<br />
	 * <br />
	 * You may also, optionally, pass in a category (primarycategoryid) to which you want this venue assigned. You can browse a full list of categories using the /categories method. On add venue, it is recommended that you show the user this categories hierarchy and allow them to choose something suitable.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/addvenue<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>name - the name of the venue</li>
	 * <li>address - (optional) the address of the venue (e.g., "202 1st Avenue")</li>
	 * <li>crossstreet - (optional) the cross streets (e.g., "btw Grand & Broome")</li>
	 * <li>city - (optional) the city name where this venue is</li>
	 * <li>state - (optional) the state where the city is</li>
	 * <li>zip - (optional) the ZIP code for the venue</li>
	 * <li>phone - (optional) the phone number for the venue</li>
	 * <li>geolat - (optional, but recommended)</li>
	 * <li>geolong - (optional, but recommended)</li>
	 * <li>primarycategoryid - (optional) the ID of the category to which you want to assign this venue</li>
	 * </li>
	 * <br />
	 * Response (truncated):
	 * <pre>{
	 *   venue:{
	 *     id:49049,
	 *     name:'Pig & Whistle',
	 *     primarycategory:{
	 *       id:79153,
	 *       fullpathname:'Nightlife:Bar',
	 *       nodename:'Bar',
	 *       iconurl:'http://foursquare.com/img/categories/nightlife/default.png'
	 *     },
	 *     address:'365 Greenwich St',
	 *     crossstreet:{
	 *     },
	 *     city:'New York',
	 *     state:'NY',
	 *     zip:10013,
	 *     phone:{
	 *     },
	 *     geolat:40.7192,
	 *     geolong:-74.0103,
	 *     stats:{
	 *       checkins:0
	 * ...
	 *     },
	 *     tips:[
	 *       {
	 * ...
	 *     ]
	 *   }
	 * }</pre>
	 * 
	 * @param name the name of the venue
	 * @param address (optional) the address of the venue (e.g., "202 1st Avenue")
	 * @param crossstreet (optional) the cross streets (e.g., "btw Grand & Broome")
	 * @param city (optional) the city name where this venue is
	 * @param state (optional) the state where the city is
	 * @param zip (optional) the ZIP code for the venue
	 * @param phone (optional) the phone number for the venue
	 * @param geolat (optional, but recommended)
	 * @param geolong (optional, but recommended)
	 * @param primarycategoryid (optional) the ID of the category to which you want to assign this venue
	 * @return added a new venue
	 * @throws FoursquareException
	 */
	Venue addVenue(CharSequence name, CharSequence address, CharSequence crossstreet, CharSequence city, CharSequence state, CharSequence zip, CharSequence phone, CharSequence geolat, CharSequence geolong, CharSequence primarycategoryid) throws FoursquareException;

	/**
	 * Propose venue edit.
	 *
	 * Allows you to flag/propose a change to a venue. If the user knows the correct address, use this method to save it. Otherwise, use /flagmislocated to flag the venue instead (you need not specify a new address or geolat/geolong in that case).<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/venue/proposeedit<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>vid - (required) the venue for which you want to propose an edit</li>
	 * <li>name - (required) the name of the venue</li>
	 * <li>address - (required) the address of the venue (e.g., "202 1st Avenue")</li>
	 * <li>crossstreet - the cross streets (e.g., "btw Grand & Broome")</li>
	 * <li>city - (required) the city name where this venue is</li>
	 * <li>state - (required) the state where the city is</li>
	 * <li>zip - (optional) the ZIP code for the venue</li>
	 * <li>phone - (optional) the phone number for the venue</li>
	 * <li>geolat - (required)</li>
	 * <li>geolong - (required)</li>
	 * </ul>
	 * Response (truncated):
	 * <pre>{
	 *   response:'ok'
	 * }</pre>
	 * 
	 * @param vid (required) the venue for which you want to propose an edit
	 * @param name (required) the name of the venue
	 * @param address (required) the address of the venue (e.g., "202 1st Avenue")
	 * @param crossstreet the cross streets (e.g., "btw Grand & Broome")
	 * @param city (required) the city name where this venue is
	 * @param state (required) the state where the city is
	 * @param zip (optional) the ZIP code for the venue
	 * @param phone (optional) the phone number for the venue
	 * @param geolat (required)
	 * @param geolong (required)
	 * @return response
	 * @throws FoursquareException
	 */
	Response proposeVenueEdit(CharSequence vid, CharSequence name, CharSequence address, CharSequence crossstreet, CharSequence city, CharSequence state, CharSequence zip, CharSequence phone, CharSequence geolat, CharSequence geolong) throws FoursquareException;

	/**
	 * Flag venue as closed
	 *
	 * Allows you to flag a venue as a 'closed' venue. The flag action will be pushed into a moderation queue. Once a venue is approved closed, it will no longer show up in search results.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/venue/flagclosed<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>vid - the venue that you want marked closed (required)</li>
	 * </ul>
	 * <br />
	 * Response:
	 * <pre>{
	 *   response:'ok'
	 * }</pre>
	 * 
	 * @param vid the venue that you want marked closed (required)
	 * @return response
	 * @throws FoursquareException
	 */
	Response flagVenueAsClosed(CharSequence vid) throws FoursquareException;

	/**
	 * Flag venue as mislocated.
	 *
	 * Allows you to flag a venue that might be geocoded improperly. The flag action will be pushed into a queue as a hint. If the user knows the correct address, use /proposeedit to save it. If they know a venue is in the wrong place, but do not know the address, it's enough to provide this mislocated hint to the system instead.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/venue/flagmislocated<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>vid - the venue that you want marked mislocated (required)<li>
	 * </ul>
	 * Response:
	 * <pre>{
	 *   response:'ok'
	 * }</pre>
	 *  
	 * @param vid the venue that you want marked mislocated (required)
	 * @return response
	 * @throws FoursquareException
	 */
	Response flagVenueAsMislocated(CharSequence vid) throws FoursquareException;

	/**
	 * Flag venue as duplicate.
	 *
	 * Allows you to flag a venue that might be a duplicate. The flag action will be pushed into a queue as a hint.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/venue/flagduplicate<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>vid - the venue that you want marked as a duplicate (required)</li>
	 * </ul>
	 * Response:
	 * <pre>{
	 *   response:'ok'
	 * }</pre>
	 * 
	 * @param vid the venue that you want marked as a duplicate (required)
	 * @return response
	 * @throws FoursquareException
	 */
	Response flagVenueAsDuplicate(CharSequence vid) throws FoursquareException;

	/**
	 * Nearby.
	 *
	 * Returns a list of tips and todos (todos are in a group called "Me" if the user is logged in) near the area specified. (The distance returned is in meters).<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/tips<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: No, but recommended<br />
	 * Parameters:
	 * <ul>
	 * <li>geolat - latitude (required)</li>
	 * <li>geolong - longitude (required)</li>
	 * <li>filter - one of "nearby" or "friends" indicating whether to return all nearby tips, or just nearby tips from friends (required, unless uid is specified)</li>
	 * <li>uid - a particular user id to get tips from (optional, see filter)</li>
	 * <li>sort - one of "nearby", "recent", or "popular" (optional, only applies if uid is specified, for which it is required)</li>
	 * <li>l - limit of results (optional, default 30)</li>
	 * </ul>
	 * <br />
	 * Response (truncated):
	 * <pre>{
	 *   tips:[
	 *     {
	 *       id:8774,
	 *       text:'The burgers here are surprisingly delicious! Order one and wait out the ten minutes by having a pleasant conversation with Margaret.',
	 *       distance:0,
	 *       created:'Thu, 30 Apr 09 23:41:27 +0000',
	 *       user:{
	 *         id:1818,
	 *         firstname:'Joe',
	 *         lastname:'LaPenna',
	 *         photo:'http://foursquare.com/userpix/1818_1239601037.jpg',
	 *         gender:'male'
	 *       },
	 *       venue:{
	 *         id:36235,
	 *         name:'KK Cafe',
	 *         address:'252 Divisadero st',
	 *         crossstreet:'Haight'
	 *       }
	 *     },
	 * </pre>
	 * 
	 * @param geolat latitude (required)
	 * @param geolong longitude (required)
	 * @param filter one of "nearby" or "friends" indicating whether to return all nearby tips, or just nearby tips from friends (required, unless uid is specified)
	 * @param uid a particular user id to get tips from (optional, see filter)
	 * @param sort one of "nearby", "recent", or "popular" (optional, only applies if uid is specified, for which it is required)
	 * @param l limit of results (optional, default 30)
	 * @return Returns a list of tips and todos (todos are in a group called "Me" if the user is logged in) near the area specified. (The distance returned is in meters).
	 * @throws FoursquareException
	 */
	TipsResult tips(CharSequence geolat, CharSequence geolong, CharSequence filter, CharSequence uid, CharSequence sort, CharSequence l) throws FoursquareException;

	/**
	 * Add tip.
	 *
	 * Allows you to add a new tip or to-do at a venue.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/addtip<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>vid - the venue where you want to add this tip (required)</li>
	 * <li>text - the text of the tip (required)</li>
	 * <li>geolat - (optional, but recommended)</li>
	 * <li>geolong - (optional, but recommended)</li>
	 * </ul>
	 * Response:
	 * <pre>{
	 *   tip:{
	 *     id:16634,
	 *     text:'Get the hamburg doria (it\'s not on the menu)',
	 *     created:'Fri, 10 Jul 09 17:17:38 +0000'
	 *   }
	 * }</pre>
	 * 
	 * @param vid the venue where you want to add this tip (required)
	 * @param text the text of the tip (required)
	 * @param geolat (optional, but recommended)
	 * @param geolong (optional, but recommended)
	 * @return response
	 * @throws FoursquareException
	 */
	Tip addTip(CharSequence vid, CharSequence text, CharSequence geolat, CharSequence geolong) throws FoursquareException;

	/**
	 * Mark tip as to-do.
	 *
	 * Allows you to mark a tip as a to-do item.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/tip/marktodo<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>tid - the tip that you want to mark to-do (required)</li>
	 * </ul>
	 * Response:
	 * <pre>{
	 *   tip:{
	 *     id:94337,
	 *     text:'good selection of port.',
	 *     created:'Tue, 24 Nov 09 21:07:41 +0000'
	 *   }
	 * }</pre>
	 * 
	 * @param tid the tip that you want to mark to-do (required)
	 * @return response
	 * @throws FoursquareException
	 */
	Tip markTipAsTodo(CharSequence tid) throws FoursquareException;

	/**
	 * Mark tip as done.
	 *
	 * Allows you to mark a tip as done.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/tip/markdone<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>tid - the tip that you want to mark done (required)</li>
	 * </ul>
	 * Response:
	 * <pre>{
	 *   tip:{
	 *     id:94337,
	 *     text:'good selection of port.',
	 *     created:'Tue, 24 Nov 09 21:07:41 +0000'
	 *   }
	 * }</pre>
	 * 
	 * @param tid the tip that you want to mark done (required)
	 * @return response
	 * @throws FoursquareException
	 */
	Tip markTipAsDone(CharSequence tid) throws FoursquareException;

	/**
	 * Unmark a tip.
	 *
	 * Allows you to unmark a tip (it will revert the previous action, if there was any on the tip). For example, if a tip was on your to-do list, it would be taken off.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/tip/unmark<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>tid - the tip that you want to unmark (required)</li>
	 * </ul>
	 * Response:
	 * <pre>{
	 *   tip:{
	 *     id:94337,
	 *     text:'good selection of port.',
	 *     created:'Tue, 24 Nov 09 21:07:41 +0000'
	 *   }
	 * }</pre>
	 * 
	 * @param tid the tip that you want to unmark (required)
	 * @return response
	 * @throws FoursquareException
	 */
	Tip unmarkTip(CharSequence tid) throws FoursquareException;

	/**
	 * Get tip details.
	 *
	 * Get the details of a tip, including who has marked it todo or done.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/tip/detail<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>tid - the tip that you want details for</li>
	 * </ul>
	 * Response (truncated):
	 * <pre>{
	 *   tip:{
	 *     id:94337,
	 *     text:'good selection of port.',
	 *     created:'Tue, 24 Nov 09 21:07:41 +0000'
	 *     done: [
	 *       user: {
	 *         ...
	 *       }
	 *   }
	 * }</pre>
	 * 
	 * @param tid the tip that you want details for
	 * @return details of a tip
	 * @throws FoursquareException
	 */
	Tip getTipDetails(CharSequence tid) throws FoursquareException;

	/**
	 * Get a list of to-dos.
	 *
	 * Get the list of to-dos for a user.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/todos<br />
	 * Formats: JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>geolat - latitude (required)</li>
	 * <li>geolong - longitude (required)</li>
	 * <li>uid - a particular user id to get tips from (optional, defaults to authenticated user)</li>
	 * <li>sort - one of "nearby" or "recent"</li>
	 * <li>l - limit of results (optional, default 30)</li>
	 * </ul>
	 * Response (truncated):
	 * <pre>{
	 *   todos:[
	 *     {
	 *       created: "Sat, 24 Jul 10 00:24:50 +0000",
	 *       todoid: "4c4a32d2bad7a5939ded04aa",       
	 *       tip:{
	 *         id:94337,
	 *         text:'good selection of port.',
	 *         created:'Tue, 24 Nov 09 21:07:41 +0000'
	 *       }
	 *     },...
	 * </pre>
	 * 
	 * @param geolat latitude (required)
	 * @param geolong longitude (required)
	 * @param uid a particular user id to get tips from (optional, defaults to authenticated user)
	 * @param sort one of "nearby" or "recent"
	 * @param l limit of results (optional, default 30)
	 * @return the list of to-dos for a user.
	 * @throws FoursquareException
	 */
	Todos todos(CharSequence geolat, CharSequence geolong, CharSequence uid, CharSequence sort, CharSequence l) throws FoursquareException;

	/**
	 * Pending friend requests.
	 * 
	 * Shows you a list of users with whom you have a pending friend request (ie, they've requested to add you as a friend, but you have not approved).<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/friend/requests<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: Yes<br />
	 * <br />
	 * Response:
	 * <pre>{
	 *   requests:[
	 *     {
	 *       id:16294,
	 *       firstname:'Benjamin',
	 *       lastname:'Bloom',
	 *       photo:'http://playfoursquare.s3.amazonaws.com/userpix_thumbs/16294_1254927789056.jpg',
	 *       gender:'male',
	 *       twitter:'bsbnyc',
	 *       facebook:401256
	 *     }
	 * ...</pre>
	 * 
	 * @return Shows you a list of users with whom you have a pending friend request
	 * @throws FoursquareException
	 */
	Requests pendingFriendRequests() throws FoursquareException;

	/**
	 * Approve friend request.
	 * 
	 * Approves a pending friend request from another user. On success, returns the user object.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/friend/approve<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * <br />
	 * Parameters:
	 * <ul>
	 * <li>uid - the user ID of the user who you want to approve</li>
	 * </ul>
	 * Response (truncated):
	 * <pre>{
	 *     user:{
	 *         id:16294,
	 *         firstname:...
	 * </pre>
	 * 
	 * @param uid the user ID of the user who you want to approve
	 * @return the user object
	 * @throws FoursquareException
	 */
	User approveFriendRequest(CharSequence uid) throws FoursquareException;

	/**
	 * Deny friend request.
	 * 
	 * Denies a pending friend request from another user. On success, returns the user object.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/friend/deny<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * <br />
	 * Parameters:
	 * <ul>
	 * <li>uid - the user ID of the user who you want to deny</li>
	 * </ul>
	 * Response (truncated):
	 * <pre>{
	 *     user:{
	 *         id:16294,
	 *         firstname:...
	 * </pre>
	 * 
	 * @param uid the user ID of the user who you want to deny
	 * @return the user object
	 * @throws FoursquareException
	 */
	User denyFriendRequest(CharSequence uid) throws FoursquareException;

	/**
	 * Send friend request.
	 *
	 * Sends a friend request to another user. On success, returns the user object.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/friend/sendrequest<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * <br />
	 * Parameters:
	 * <ul>
	 * <li>uid - the user ID of the user to whom you want to send a friend request</li>
	 * </ul>
	 * Response (truncated):
	 * <pre>{
	 *   user:{
	 *     id:16294,
	 *     firstname:...
	 * </pre>
	 * 
	 * @param uid the user ID of the user to whom you want to send a friend request
	 * @return
	 * @throws FoursquareException
	 */
	User sendFriendRequest(CharSequence uid) throws FoursquareException;

	/**
	 * Find friends by name.
	 * 
	 * When passed a free-form text string, returns a list of matching user objects. The method only returns matches of people with whom you are not already friends.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/findfriends/byname<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: Yes<br />
	 * <br />
	 * Parameters:
	 * <ul>
	 * <li>q - the string you want to use to search firstnames and lastnames</li>
	 * </ul>
	 * Response (truncated):
	 * <pre>{
	 *     users:[
	 *         {
	 *             id:16294,
	 *             firstname:'...'
	 *         }
	 * </pre>
	 * 
	 * @param q the string you want to use to search firstnames and lastnames
	 * @return list of matching user objects.
	 * @throws FoursquareException
	 */
	Users findFriendsByName(CharSequence q) throws FoursquareException;

	/**
	 * Find friends by phone.
	 * 
	 * When passed phone number(s), returns a list of matching user objects. The method only returns matches of people with whom you are not already friends. You can pass a single number as a parameter, or you can pass multiple numbers separated by commas.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/findfriends/byphone<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: Yes<br />
	 * <br />
	 * Parameters:
	 * <ul>
	 * <li>q - the string you want to use to search for phone numbers</li>
	 * </ul>
	 * Response (truncated):
	 * <pre>{
	 *   users:[
	 *     {
	 *       id:16294,
	 *       firstname:'...'
	 *     }
	 * </pre> 
	 * 
	 * @param q the string you want to use to search for phone numbers
	 * @return list of matching user objects
	 * @throws FoursquareException
	 */
	Users findFriendsByPhone(CharSequence q) throws FoursquareException;

	/**
	 * Find friends by using a Twitter name.
	 * 
	 * When passed a Twitter name (user A), returns a list of matching user objects that correspond to user A's friends on Twitter. The method only returns matches of people with whom you are not already friends.<br />
	 * <br />
	 * If you don't pass in a Twitter name, it will attempt to use the Twitter name associated with the authenticating user.<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/findfriends/bytwitter<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): GET<br />
	 * Requires Authentication: Yes<br />
	 * <br />
	 * Parameters:
	 * <ul>
	 * <li>q - (optional) the Twitter name you want to use to search</li>
	 * </ul>
	 * Response (truncated):
	 * <pre>{
	 *   users:[
	 *     {
	 *       id:16294,
	 *       firstname:'...'
	 *     }
	 * </pre>
	 * 
	 * @param q (optional) the Twitter name you want to use to search
	 * @return list of matching user objects
	 * @throws FoursquareException
	 */
	Users findFriendsByTwitter(CharSequence q) throws FoursquareException;

	/**
	 * Set pings
	 * 
	 * Allows you to change notification options for yourself (self) globally as well as for each individual friend (identified by their uid).<br />
	 * <br />
	 * For example: To set pings on for a user identified by UID 33: "33=on". To set pings to 'off' for yourself: "self=off".<br />
	 * <br />
	 * URL: http://api.foursquare.com/v1/settings/setpings<br />
	 * Formats: XML, JSON<br />
	 * HTTP Method(s): POST<br />
	 * Requires Authentication: Yes<br />
	 * Parameters:
	 * <ul>
	 * <li>self - the ping status for yourself (globally). possible values are on and off.</li>
	 * <li>[uid] - set the ping status for a friend. possible values are on and off.</li>
	 * <ul>
	 * Response:
	 * <pre>{
	 *   settings:{
	 *     pings:'on'
	 *   }
	 * }</pre>
	 * 
	 * @param self the ping status for yourself (globally). possible values are on and off.
	 * @param uid set the ping status for a friend. possible values are on and off.
	 * @return response
	 * @throws FoursquareException
	 */
	Settings setPings(CharSequence self, CharSequence uid) throws FoursquareException;
}